Summary

Type-system shape for the lockstep cutover of LibreChat ↔ codeapi sandbox file identity. Two distinct concepts had been sharing the field name session_id; this PR also adds the kind discriminator so codeapi's sessionKey derives from explicit resource type rather than emergent legacy behavior.

Companions: codeapi #1455, LibreChat #12960. Pre-release lockstep, no legacy aliases.

Bumps to 3.1.80-dev.0.

Final shape

export const CODE_ENV_KINDS = ['skill', 'agent', 'user'] as const;
export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];

export type CodeEnvFile =
  | (Base & { kind: 'skill'; version: number })
  | (Base & { kind: 'agent' })
  | (Base & { kind: 'user' });

type Base = {
  /** sessionKey-meaningful for `'skill'` / `'agent'`; informational
   *  only for `'user'` (codeapi resolves user from auth context). */
  id: string;
  name: string;
  /** Long-lived storage bucket, distinct from top-level execution session. */
  storage_session_id: string;
};

What's in this PR

1. Per-file session_id → storage_session_id rename. Top-level session_id (transient sandbox-run id on CodeSessionContext, ExecuteResult, ProgrammaticExecutionResponse, etc.) keeps its name — only the misnamed side moves. Hard rename, no aliases.
2. kind discriminator added to CodeEnvFile (required) and FileRef (optional, since /files fallback may not carry it). Drives codeapi's per-resource sessionKey: <tenant>:<kind>:<id>[:v:<version>] for shared kinds, <tenant>:user:<userId> for user-private.
3. Discriminated union on CodeEnvFile: version: number is statically required for kind: 'skill' and statically forbidden for 'agent' / 'user'. Constraint holds at compile time on every consumer, not just at codeapi's runtime validator.
4. CODE_ENV_KINDS const-tuple — adding a new kind to the tuple updates both the runtime list and the TS union at once, so a partial update can't silently widen one side.
5. Drops entity_id from CodeEnvFile, FileRef, and ToolNode propagation. Drops 'system' from the kind union (no emitter ever existed).
6. toInjectedFileRef helper in ToolNode: collapses the two near-identical CodeEnvFile constructors (the runTool injection path and the event-driven getCodeSessionContext path) onto one call site that does the discriminated-union narrowing in one place. Defaults missing-kind to 'user'; a skill ref missing version falls back to 'user' so an upstream contract bug surfaces as a degraded sessionKey rather than a runtime crash.
7. JSDoc on id calls out the per-kind asymmetry; on version documents the 'skill'-only requirement.

Sites updated

• src/types/tools.ts — CodeEnvKind, CODE_ENV_KINDS, discriminated CodeEnvFile, JSDoc on FileRef.
• src/tools/ToolNode.ts — toInjectedFileRef helper at runTool injection (_injected_files) and getCodeSessionContext. updateCodeSession and storeCodeSessionFromResults pass new fields through via spread.
• CodeExecutor, BashExecutor, ProgrammaticToolCalling, BashProgrammaticToolCalling, LocalExecutionTools, LocalProgrammaticToolCalling — per-file refs use storage_session_id; top-level session_id extraction unchanged.
• Tests: ToolNode.session.test.ts repurposed entity_id-forwarding cases as kind + version forwarding cases (the actual Phase C contract).

Test plan

• npx tsc --noEmit clean
• npx jest src/tools src/types — 787 / 787 pass (incl. 18 session-management tests with new per-file shape)
• Manual: bump LibreChat's @librechat/agents dep to 3.1.80-dev.0 after this lands and run a multi-turn execute against codeapi to confirm.

Why no legacy aliases

The deployment matrix is controlled — codeapi service + LC's pinned @librechat/agents version + LC itself all ship together. A synchronized cutover is fine; alias plumbing for a deploy ordering that doesn't exist is just code to maintain and clean up.

Why keep top-level session_id

Renaming both sides was symmetric but unnecessary. The bug was that per-file session_id was the wrong name (it really meant "storage"). Top-level session_id is the right name (it really means "session"). Disambiguating only the misnamed side gives ~half the churn at every call site, and a future engine that uses one session concept lands on session_id directly with no rename to undo.